.TH Rid 3 "September 2017" "Version 1.0" "librid_fn85 API"
.SH NAME
rid_fn85 \- Rid fn85 encoded string library.
.SH SYNOPSIS
.B #include <rid_fn85.h>
.sp
Link with \fI\-lrid_fn85\fP \fI\-lfn85\fP \fI\-lrid\fP and \fI\-lbsd\fP or `pkg-config --libs rid_fn85`
.SH DESCRIPTION
A library to convert Rids to fn85 encoded strings.
.sp
.SS Defines
.B RID_FN85_LEN
is the length of a fn85 encoded Rid, it does not include the '\e0'. This would be the same value as calling
.B strlen ()
on a fn85 encoded string of a Rid.
.sp
.SS Types
.B Rid_fn85
is a char array big enough for a string containing a fn85 encoded Rid. It can hold 20 fn85 encoded digits plus a tailing '\e0'. It is defined as:
.sp
typedef char Rid_fn85[21];
.sp
.B Rid_fn85_path
is similar to
.BR Rid_fn85 ","
except a '/' is inserted after the each of the first two digits. This is done to provide a relative path for using Rids as file names since some file systems have issues with having many files in a single directory. It is defined as:
.sp
typedef char Rid_fn85_path[23];
.SS Functions
.BI "void rid_fn85(char *" str ", const Rid " id ");"
.br
.BI "Fn85_err rid_fn85_parse(Rid " id ", const char *" str ", size_t *" pos ", const char **" error ");"
.br
.BI "void rid_fn85_path(char *" path ", const Rid " id ");"
.sp
.B rid_fn85 ()
.RI "converts " id " to a fn85 string stored in " str "."
.sp
.B rid_fn85_parse ()
.RI "converts " str " to binary stored in " id ". " pos " is increased by the number of valid digits before an error occurs and must be initialized prior to calling the function. If no error occurs, it is increased by "
.BR RID_FN85_LEN "."
.RI "If an error has occured and " error " is not NULL, " error " is set to an appropriate error message."
.sp
.B rid_fn85_path ()
.RI "converts " id " to a path suitable for a file name stored in " path "."
.SH "Return Value"
The function
.B rid_fn85_parse ()
returns a value of type
.B Fn85_err
which denotes if an error occured in decoding, and if so, what said error was. The value
.B FN85_OKAY
denotes no error has occured and also that an error message has not been set.
.SH EXAMPLES
.SS Creating a Rid path in a subdirectory
This can be done by passing a pointer to the last 21 bytes of a string to
.B Rid_fn85_path
.RI "for the " path " argument. See the example program below:"
.sp
.nf
#include <rid.h>
#include <stdio.h>
#include <string.h>

#include <fn85.h>
#include <rid_fn85.h>

/* define the directory we want to generate our Rid paths in */
#define DAT_DIR "dat/"
/* define the number of characters in DAT_DIR minus the '\0' */
#define DAT_DIR_LEN (sizeof(DAT_DIR) - 1)

/* A type for a string big enough for our path */
typedef char Dir_path[DAT_DIR_LEN + sizeof(Rid_fn85_path)];

int
main(int argc, char *argv[])
{
	Rid id;
	Dir_path dir_path;

	/* create a random rid */
	rid_set(id, NULL);
	/* set the dat/ part of the path */
	strcpy(dir_path, DAT_DIR);
	/* generate the rest of the path */
	rid_fn85_path(dir_path + DAT_DIR_LEN, id);

	/* Now we can do anything we want with dir_path, it's just a string
	 * that looks something like "dat/</L/5E0HTCJ*`tp*(Y;eW)"
	 */

	printf("%s\en", dir_path);

	return 0;
}
.fi
.SS Converting, Parsing, and Comparing Rids
.nf
#include <rid.h>
#include <stdio.h>
#include <string.h>

#include <fn85.h>
#include <rid_fn85.h>

int
main(int argc, char *argv[])
{
	Rid id1;
	Rid id2;
	Rid id3;
	Rid_fn85 str1;
	Rid_fn85 str2;
	size_t pos = 0;
	const char *error;

	/* set both id1 to a random value */
	rid_set(id1, NULL);

	/* copy id1 into id2 */
	rid_set(id2, id1);

	/* convert Rids to strings */
	rid_fn85(str1, id1);
	rid_fn85(str2, id2);

	/* and they will produce equal strings if they have the same value */
	if (!strcmp(str1, str2))
		printf("that only makes sense.\en");

	/* we can also get an Rid from a string */
	if (rid_fn85_parse(id3, str1, &pos, &error) == FN85_OKAY) {
		printf("%s\en", str1);
	} else {
		printf("%s at %zu\en", error, pos);
	}

	if (!rid_cmp(id3, id1))
		printf("this will also be printed!\en");

	/* and that's all there is to it! */
	return 0;
}
.fi
.SH AUTHOR
Uladox (more please for Rids)
.SH "AVAILABILITY AND SOURCE"
.B rid_fn85
can be found in its repository at https://www.notabug.org/Uladox/rid_fn85
.SH "SEE ALSO"
.BR rid (3)
.BR fn85 (3)
.BR rid_hex (3)

